home *** CD-ROM | disk | FTP | other *** search
/ The 640 MEG Shareware Studio 2 / The 640 Meg Shareware Studio CD-ROM Volume II (Data Express)(1993).ISO / clang / zcpp_jae.zip / README < prev    next >
Text File  |  1990-07-10  |  9KB  |  175 lines
  1. -*- Mode:Text -*-
  2.  
  3. Summary of CPP Macro Support
  4.  
  5. This is a summary of the defmacro language extension, its syntax and
  6. capabilities, and examples of usage.  I have composed this in an attempt to
  7. provide a gentler introduction than that available in the man page.  Note that
  8. the following implementation details are *NOT* standard C++, but rather
  9. extensions that we have added via an enhanced, portable preprocessor.  This
  10. preprocessor has been brought up on Sun OS, SCO XENIX, OS/2, and MVS.
  11.  
  12. There are lots of pieces to the macro facilities.  Some were patterned after
  13. LISP features such as LOOP and REST: arguments, while others such as the
  14. parameterized types support are implementations of design papers published by
  15. Stroustrup.  Together, they provide significant language features and enhanced
  16. power for the programmer.  However, it is important to note that once any
  17. given macro is expanded, the resulting code is plain-old vanilla C++ syntax
  18. acceptable to any C++ translator or compiler.
  19.  
  20. The basic cpp extension mechanism utilized to implement all macro
  21. functionality is provided by a #pragma statement.  Common macros are defined
  22. in this manner.  The "defmacro" keyword follows and provides a way to execute
  23. arbitrary filter programs (macros expanders) on code fragments.  The syntax
  24. for defmacro is:
  25.  
  26.      #pragma defmacro name <file> options
  27.  or  #pragma defmacro name "file" options
  28.  or  #pragma defmacro name program options
  29.  
  30. where "name" is the name of the filter, <file> and "file" are the name of a
  31. source file containing a macro definition, "program" is the name of a program
  32. implementing a macro, and options is a series of of optional modifiers for the
  33. defmacro explained below.  The implementation of a defmacro may be either
  34. external to the preprocessor (as in the case of files and programs) or
  35. internal to the preprocessor.  For example, the template macro implementing
  36. parameterized types is internal to the preprocessor to provide a more
  37. efficient, performance tuned implementation.  Cpp will first search for a file
  38. or program in the same search path as that used for include files.  If a match
  39. is not found, it then searches an internal preprocessor table.  If a match is
  40. still not found, cpp prints "Error: Cannot open macro file [xxx]", where "xxx"
  41. is the name as it appears in the source code.
  42.  
  43. The defmacro syntax also supports a series of options.  Zero or more of the
  44. following options may be included in any order:
  45.  
  46.      recursive    - when present, the macro may be recursively expanded.
  47.  
  48.      expanding    - when present, input to the macro is expanded.
  49.  
  50.      delimiter=x  - the default delimiter (semicolon) is replaced with 'x'.
  51.  
  52.      other        - unknown options are passed as arguments to the macro
  53.             expander.
  54.  
  55. When a defmacro style macro is encountered by the preprocessor, the name and
  56. everything until the terminating character -- including all matching and
  57. nested levels of {} [] () <> "" '' and comments found along the way -- is
  58. piped into the macro procedure's standard-input.  The procedure's standard
  59. output is scanned by CPP for further processing.  The resulting expansion
  60. replaces the macro input in the source.
  61.  
  62.  
  63. The defmacro implementation is used to declare the MACRO (all uppercase)
  64. keyword.  This is essentially an enhanced #define syntax that supports
  65. multiline, arbitrary length, nested macros and cpp-directives, with optional,
  66. keyword, and body parameters.  To use it include the line:
  67.  
  68.      #pragma defmacro MACRO "macro" delimiter=}
  69.  
  70. thus declaring the MACRO keyword whose implementation is a cpp internal
  71. routine named "macro".  The terminating delimiter for a MACRO is the closing
  72. brace character.  The syntax for MACRO is:
  73.  
  74.      MACRO name (arglist) { body }
  75.  
  76. where "name" is the name of the macro, "arglist" is a list of argument
  77. specifiers separated by commas, and "body" is what is substituted on a call to
  78. the macro.  The "arglist" may specify positional, optional, optional keyword,
  79. required keyword, rest and body arguments.  When KEY: is specified, the macro
  80. takes all following arguments to be keyword arguments that allow the user to
  81. specify a particular value.  Default values are support by use of an equal
  82. sign and value and may be applied to both regular and keyword arguments.  The
  83. REST: modifier indicates that there is some number of arguments, all of which
  84. are referenced by use of the one named identifier.  An optional equal sign and
  85. identifier will contain the number of arguments remaining.  Finally, BODY:
  86. indicates that when used, the parameter will be expanded to include all the
  87. text within the braces after the macro call.  This is useful for identifying a
  88. section of code that implements some part of the macro or should be passed to
  89. other nested macros.  The following examples show some of the power and
  90. flexibility of the COOL MACRO capability:
  91.  
  92.      MACRO set_val (size, value=NULL, KEY: low = 0, high) {
  93.        init (size, value, low, high-low)
  94.      }
  95.  
  96. In this example, "set_val" is the name of the macro that the programmer refers
  97. to, "size" is a required positional argument, "val" is an optional positional
  98. argument that if not specified in a particular call has a default value of
  99. NULL, "low" is an on optional keyword parameter, and "high" is a required
  100. keyword parameter.  In this example, the macro simple calls the function
  101. init() with four arguments.  The following show several legal invocations of
  102. the macro along with the resulting call to the function init():
  103.  
  104.      set_val (0, high=20)         ---->   init (0, NULL, 0, 20);
  105.      set_val (0, low=5, high=15)  ---->   init (0, NULL, 5, 10);
  106.      set_val (1, 2, high=25)      ---->   init (1, 2, 0, 25);
  107.  
  108. See the files "macro-sample.c" and "macro-sample.i" for an example usage of
  109. this capability and the corresponding expansion.
  110.  
  111.  
  112. One of the main uses of the defmacro facility is the implementation of
  113. templates to support parameterized types.  The syntax of the template grammar
  114. is that as specified by Stroustrup in his paper "Parameterized types for C++"
  115. in the 1988 USENIX C++ Conference Proceedings.  Cpp implements this
  116. functionality such that there will be minimal source code conversion necessary
  117. when this feature is finally implemented in the C++ language.
  118.  
  119. A class programmer who wishes to implement a vector class object wants to make
  120. design and implementation decisions in such a way as to facilitate a simple
  121. and consistent interface for the application programmer, no matter what type
  122. of thing is to be stored in the vector.  In addition, replication of code for
  123. each specific type should be avoided if at all possible.  To accomplish this,
  124. the class programmer implements a vector template, with the type selection
  125. left to the application programmer.  The following example is for a Vector
  126. header file:
  127.  
  128.         template<class Type> class Vector { // Parameterized Vector class
  129.         private:
  130.           Type* v;                          // Data of type pointer to Type
  131.           int size;                         // Size of vector object
  132.         public:
  133.           Vector ();                        // Empty constructor
  134.           Vector (int);                     // Constructor with size
  135.           Vector (Vector&);                 // Constructor with reference
  136.           ~Vector ();                       // Destructor
  137.           Type& operator[](int n);          // Operator[] overload for Type
  138.           Type& element (int n);            // Return element of type Type
  139.           ...                               // ... other methods ...
  140.         };
  141.  
  142. An application programmer would include this header file in the appropriate
  143. source file.  In addition, common header file must be included to provide the
  144. #pragma statement declaring the defmacro template shown below.  This must
  145. occur before the inclusion of the Vector header file and so is done within
  146. Vector.h if it has not already been included.
  147.  
  148.     #pragma defmacro template "template" delimiter=}
  149.  
  150. An application programmer also places the following lines in his/her source
  151. code to use the parameterized Vector class for a specific type:
  152.  
  153.         DECLARE Vector<double>;
  154.     IMPLEMENT Vector<double>;
  155.         Vector<double> vs(30);        
  156.  
  157. The DECLARE macro implements a series of #define preprocessor statements that
  158. will declare and define code for a Vector of doubles.  Together with the
  159. template macro expander.  A class definition with its associated methods is
  160. created ready to be compiled, all performed invisibly to the user.
  161.  
  162. The common header file must include the #pragma statements that allow DECLARE
  163. and IMPLEMENT to work also.  They are as follows:
  164.  
  165.     #pragma defmacro MACRO "macro" delimiter=} recursive
  166.     #pragma defmacro DECLARE "declare" delimiter=> recursive lines
  167.     #pragma defmacro IMPLEMENT "implement" delimiter=> recursive lines
  168.  
  169. See the files "template-sample.c" and "template-sample.i" for an example usage
  170. of this capability and the corresponding expansion.
  171.  
  172. There are several other internal macros included with cpp that we have
  173. experimented with.  These can safely be ignored.  For the interested parties
  174. who want to delve more we refer you to the comments in the source files.
  175.